第 6 小节：提交第一个 Issue

什么是 Issue

Issue 的翻译大致为议题、问题。

issue的翻译

为了方便你理解，我们更愿意把它称之为待办清单、问题或 Bug 列表、讨论版等等。相信这些称呼会让你更容易理解什么是 Issue。

这是一种伟大的协作方式，让你可以更方便的对整个仓库进行跟踪、增强和排错[1]。对于一个公开的仓库来说，Issue 是向所有人开放的，不仅仓库的所有者可以给自己提 Issue，其他人也可以对项目提 Issue。

而根据 Gitee 官方的建议，项目相关的技术问题、缺陷报告、建议等信息都可以通过 Issue 进行发布。

什么情况下需要提交 Issue

那么什么情况下需要提交 Issue 呢？

常见的 Issue 面板的使用会有以下几种方式：

  1. 待办清单 TO DO LIST

    比如你要写一本书，共分为八个章节，你选择使用 Gitee 来管理你的书籍电子稿。那么你需要提前想好每一章节的标题，以及每个章节内的每个小节需要写点什么，并列个提纲。此时，你可以将每一个小节想好要写的大致脉络分别提一个 Issue，用来提醒自己未来要做的事情。（这也是你正在看的这本开源指北的协作方式）完成后，你只需要按照规划，将每一个 Issue 中所提到的编写任务完成，你的云端书籍也就完成了。

  2. 问题列表 BUG LIST

    一个复杂的项目难免会有这样或那样的 Bug，而这些内容被观摩你仓库的朋友们发现之后，可以通过 Issue 给你提出，你可以根据他们指出的复现步骤来定位问题，并最终修复，让你所编写的项目更加健壮而强大。不要害怕自己代码写得很烂，感觉别人提 Bug 就是在揭自己的短什么的，因为每发现一个 Bug 意味着你的程序又少了一个缺陷，只需要快速修复它即可。当然，你也可以自己发现 Bug，并给自己提出 Issue，目的是让自己的项目有充分的留痕，便于后续避免该问题或寻找解决方案。

  3. 讨论版 BBS

    可以完全将 Issue 模块当做你的仓库的私人论坛、私人社区来使用。围绕你的项目，你可以做如下的事情：

    • 提出你下一阶段想要添加的功能，请大家集思广益，这样会非常有利于知识和技术的沉淀，即使是当时没有参加讨论的开发者，事后也可以通过该 Issue 了解进行此功能设计的前因后果。
    • 其他人有事想对作者询问、探讨，或咨询如何使用
    • 其他人想要作者添加点新功能，提出来跟作者讨论讨论
    • 甚至，你也可以在 Issue 里给广大开发者提跟你的仓库内容完全无关的事情，比如：求助！女朋友生气了要怎么哄？

    当然，第三点的前提是这是你自己的仓库，如果是他人的仓库，请遵守其作者对于 Issue 板块的要求和规定。前文也提到，根据 Gitee 官方的建议，可以通过 Issue 进行发布的内容包括项目相关的技术问题、缺陷报告、建议等信息，这一点请开发者们着重注意，避免一些项目外的信息影响 Issue 板块的正常讨论。

所以，总结下来，可以有如下结论：

  • 对于你自己来说，可以使用 Issue 来发布待办清单，给自己提开发任务或 Bug，开帖找大家探讨项目下一步的发展方向等等。当然，你也可以用它来提出一些跟仓库内容无关的事情，这也是允许的。
  • 如果你想要提 Issue 的仓库不是你自己的，而是他人的的时候，Issue 就是一个很好的多人协作系统。比如发现了别人项目的 Bug 的时候；比如想要别人添加某个新功能的时候；比如有使用上的困难，需要求助作者使用步骤的时候，你都可以给别人的仓库提出 Issue。同时，如果你是一个热心的开发者，你也可以帮助原作者回答一些别人提出的 Issue，这样的行为可以极大地帮助原作者分担压力哦。不要觉得自己是在做临时免费工，解答的过程中你的知识和技术也会得到巩固和提高，有时还能结交到许多志同道合的好朋友哦。我助人，人亦助我。

一个好的 Issue 应该写些什么

那么一个好的 Issue 应该写点什么呢？

这一点对于外部协作者来说尤为重要，因为你要提的 Issue 不是在自己的地盘上，而是需要得到别人的帮助的，所以你尤其要注意 Issue 的礼仪。

Issue 的礼仪[2]

  1. 提问使用的语言：在主要面向母语为中文的开发者的开源平台，首选中文。在其他开源平台，首选仓库维护者的母语进行交流，如果不确定或有困难，建议选择英文交流。
  2. 提问态度和语气：因为你面对的是跟你一样的开发者，不卑不亢，虚心求教就可以了，不必要太咋呼，措辞太夸张等。但是言语之间要表示对作者的尊重，最好多使用请、谢谢、Please、Thanks等词语。
  3. 如有 Issue 模板，请参照模板写 Issue。如果原作者定义了 Issue 模板，请按模板来写，避免挤牙膏式的交流。如没有，本文会有比较通用的模板提供给大家。总之，撰写的原则是，把事情表述清楚，便于原作者处理和与你交流。

一个好 Issue 的标准[2]

  1. 避免使用术语或晦涩的文字，尽量不要堆砌术语即可，不是说禁止使用术语；
  2. 问题可以切分，也就是说可以逐步解决的问题；
  3. 尽量跟其他问题没有瓜葛，依赖其它问题会降低处理的灵活性；
  4. 可以协商，也就说我们有好几种办法达到目标；
  5. 问题足够小，可以非常容易的评估出所需时间和资源；
  6. 可衡量，我们可以对结果进行测试。

如果你是仓库的拥有者，你还可以编写一个 CONTRIBUTE.md 文件放在项目中，用来告知其他开发者需要如何参与你的项目。

Issue 的标题怎么写？[2]

格式：[分类、标签或某文件名] + 简短描述

先使用方括号（也可以使用【】替代方括号），里面写上分类、标签或某文件名（比如这个文件有问题待修改），这部分是便于作者进行问题分类的，也方便其他协作者查找（很多人提 Issue 并没有这一部分，建议加上）。然后使用简短的描述，可以让人通过标题快速了解这个 Issue 是讲什么内容的。

案例：[Bug]app.py文件 173 行运行报错，疑似遗漏一个=号

提出一个 Issue

咱们先来给一个 Gitee 官方通用的模板：

  1. ### 该问题是怎么引起的？
  5. ### 重现步骤
  9. ### 报错信息

你可以按照模板来补充 Issue 内容，如果你有更详细的描述，当然也可以扩充模板。如果作者有提供 Issue 模板，请按照作者规定的模板提，这样可以方便作者对问题进行后续整理。

Gitee 在提 Issue 时是支持 Markdown 格式的，它让我们提出的 Issue 能有更加丰富的内容展现。

在 Gitee 中，支持在新建仓库时创建 Issue 模板，也支持自定义模板。

在新建仓库时，勾选使用Issue模板文件初始化这个项目，实际上就是在仓库根目录下新建了 .gitee/ISSUE_TEMPLATE.zh-CN.md 文件，当然你也可以自己创建这个文件，来编写自己的模板。

选择使用模板来初始化项目

自己创建 Issue 模板，可在仓库中创建.gitee目录，并创建对应的模板文件：

  1. .gitee/ISSUE_TEMPLATE.zh-CN.md，Issue 中文模板
  2. .gitee/ISSUE_TEMPLATE.en.md，Issue 英文模板
  3. .gitee/ISSUE_TEMPLATE.zh-TW.md，Issue 繁体模板

Q: 不同类型的模板，有什么作用？

A: 例如你的仓库中有 3 种语言类型的 Issue 模板，提交 Issue 的用户使用的是英文版，那么当用户勾选使用Issue模板，则会智能地使用英文模板，如果对方使用的是中文版则会智能地使用中文 Issue 模板。

当你在敲标题或者 Issue 内容时，项目会自动显示已有的类似 Issue，你可以先查看一下推荐的 Issue 能否解决你的问题，如果不能再提出，避免反复提出同一个问题。

好了，当你完成 Issue 主体内容的填写之后，快去提交给作者吧！

Issue 案例（有价值和无价值）

下面我们来看几个 Issue 的案例。

无价值：

https://gitee.com/sentsin/layui/issues/I1SS5Z

无价值案例 1

该案例的标题仅两个字表格，作者如果不点进 Issue 的具体内容则无法获知到底这个 Issue 说的是什么。属于无价值案例。

https://gitee.com/sentsin/layui/issues/I1PQVC

无价值案例 2

该案例最抓人眼球的应该是那一长串的!号，画面都快容不下了，而且作者在看这样的标题的时候也无法获知到底是个什么问题，有一种过分夸张的感觉。属于无价值案例。

有价值：

https://gitee.com/sentsin/layui/issues/I1OFU3

有价值案例 1

标题清晰明了，作者可以轻松获知 Issue 的主体内容。内容贴出了自己尝试的代码，便于作者提供帮助。属于有价值案例。

https://gitee.com/sentsin/layui/issues/I1OD1P

有价值案例 2

该案例同样使用了清晰明了的标题表述形式，内容中还具体贴出了自己尝试的代码，便于作者提供帮助或定位问题。属于有价值案例。

从上面的几个简单的案例来看，我们发现无价值的案例都有过分夸张、需要表达的观点或内容不清晰等问题。

而有价值的案例，既能在标题中精准反馈某一个点的问题，又能在内容中贴出自己尝试的代码和想法，便于作者提供帮助。

因此，Issue 的精准表述是能获得良好协作的基础，提 Issue 也是一种很好的练习表达的方式。

Issue 的进阶使用

掌握了 Issue 的基础使用之后，作为一个优秀的开发者，我们还可以掌握一些进阶的知识，它能让你压榨干净 Issue 的每一分价值。

Issue 的详细设置

如果仓库是你自己的，你可以在每一个 Issue 的面板看到更多的进阶选项，如图所示：

Issue的进阶设置

  • 负责人：负责人指的是谁来负责处理这个 Issue，可以设置用户为负责人或协作者。对于个人版来说，只能选择自己。如果是组织或者企业，可以指派他人。同一个 Issue 仅能有一个负责人，但问题可能由多个人协作解决，所以可以添加多个协作者。其它权限是一样的。对于企业版用户来说，设置负责人可以很好地统计任务完成情况（个人版无此功能，因此负责人也可以不设置），如图所示：

    组织或企业的负责人选择

    企业版中可根据负责人统计任务完成信息：

    企业版中可根据负责人统计任务完成信息

  • 标签：高质量的 Issue 是项目成功的关键。有些人把 Issue 仅仅看作是一堆你不得不去处理的问题列表，但是如果这些问题单管理完善，进行了分类并打上标签，会令人意想不到的提升我们对代码和社区的了解程度，也让我们更清楚问题的关键点在哪里。[2]将标签完善之后，不管是仓库所有者还是其他人都可以快速定位含有某标签的 Issue，协作的效率也将大大提高。

    在 Gitee 中，Issue 中的标签支持修改原有标签名称、从其它项目导入标签以及新增自定义标签等。一个默认的仓库会有如下一些默认的标签[2][3]：

    Issue中的默认标签

    如果默认的标签不够你使用，你可以添加你的自定义标签。只需要点击右上角的+号即可。

  • 项目：项目仅企业版用户可以关联，个人版或组织在这一项可以忽略掉。企业版用户可以根据下面的图片来了解如何创建一个项目，以及如何找到新创建的项目。当项目创建之后，就可以关联到某个 Issue 了。

    先进入企业面板，进入所在企业：

    先进入企业面板，进入所在企业

    右上角新建项目可以新建：

    右上角新建项目可以新建

    查看新建的项目：

    查看新建的项目

  • 里程碑：里程碑是某功能或某个时间段的一堆问题的集合。比如我们要写一本书，一个章节如果设置为一个里程碑，那这个章节里面的每一个小节我们就可以分别提多个 Issue，最后将这些 Issue 关联到这个章节的里程碑中，方便管理，可以很容易看到整个章节的完成进度。我们可以根据自己的需要，来使用里程碑的功能。下面是一些使用里程碑功能的例子[1]：

    • 发布测试——在你发布项目的 Beta 版之前，包含你需要修复的 Bug 文件相关的 Issue。这样可以确保你不会漏掉什么。
    • 十月冲刺——记录你在十月份应该做的问题清单。相当于一个工作清单，时刻提醒你应该重点完成哪些工作。（当然，你设定一个九月要做的事情的清单也是可以的）
    • 重新设计——记录与重新设计项目的问题清单。这是一种收集灵感的好方法。

    如何创建自己的里程碑？（所有用户均可创建）

    新建里程碑：

    新建里程碑

    新建完成后即可在 Issue 中关联：

    新建完成后即可在 Issue 中关联

  • 关联分支：这里可以选择关联到该仓库的哪个分支。

    选择关联分支

  • 计划开始日期：该 Issue 计划开始处理的日期。

  • 计划截止日期：该 Issue 计划截止处理的日期。

  • 置顶选项：该 Issue 在 Issue 列表中的置顶级别。

    置顶选项

  • 优先级：该问题的严重程度，优先处理级别。

    优先级

Issue 的状态和看板

Issue 在提出之后，对于个人版来说可以有四种状态：待办的、进行中、已完成、已拒绝。负责人或者协作者可以修改该状态。企业版会可选更多的状态。

状态变更之后，允许再次变更，比如设置为已完成状态的 Issue，可以再次修改为进行中。

Issue 的状态切换

我们还可以在看板中看到处于每种状态的 Issue 的列表。

看板页面

@ 提及别人

使用@符号可以在 Issue 提出或者问题讨论的过程中提及别人，起到被 艾特的效果。

# 关联其他 Issue

使用#符号再加上其他 Issue 的编号，可以关联到其它的 Issue。找到本仓库下 Issue 的编号之后写上即可。

找到 Issue 编号（这里为 #I23WUE）：

找到 Issue 编号

支持快速点击，提交 Issue 之后会自动生成链接，链接到该 Issue：

支持快速点击

通过筛选器快速找到 Issue

可以通过搜索框输入关键词搜索 Issue，也可以通过下方的一些搜索条件来搜索 Issue。有了筛选器，当我们的 Issue 非常多时，我们就可以在众多的 Issue 中找到自己需要的 Issue 了。

当你将各种 Issue 维护好对应的标签之后，可以快速找到属于某个标签的 Issue 结果进行处理。

快速搜索 Issue

在 Commit 中关闭 Issue

比如在修复一个 Bug 时，某一次 Commit 就是解决了提这个 Bug 的 Issue 的，那么我们可以轻松的在 Commit 的内容中附带上一些特殊信息（在 Commit 信息中或者附加信息中均可），来自动关闭 Issue。

Gitee 支持的提交方式有（比如我们需要关闭的 Issue 编号为 24，+号表示在提交的内容中添加后面部分的内容）[4]：

  1. # 任选其一即可！
  2. + fix #24
  3. + fixed #24
  4. + close #24
  5. + closes #24
  6. + closing #24
  7. + closed #24
  8. + resolved #24

在提交的内容中添加关闭 Issue 的信息

Issue 中的待办清单

不知道大家是否在 Issue 中有一些任务需要分步骤完成呢？如下面示例的 Issue，可以实现待办清单的功效[4]。可以根据后续的需要，勾选或者取消勾选待办清单中的分项任务，实现 checklist 的效果。

勾选或取消勾选后，刷新页面或者关闭该 Issue 页面重新打开，选择的状态依然存在，而且这种操作会保存到该 Issue 的操作日志当中去。修改状态，不再需要重新编辑该 Issue 了，非常的方便。

Issue待办清单效果演示

那么，需要拥有这样的待办清单，提 Issue 的时候应该怎么写呢？请看代码：

  1. 通过特有的语法可以实现待办清单的功效，修改待办清单里面的项目是否完成无需再打开 Issue 的编辑界面了！
  3. * [x] 吃早餐
  5. * [ ] 吃午餐
  7. * [ ] 吃晚餐

通过* [x]来创建已勾选的事项，通过* [ ]来创建未勾选的事项即可。

请注意，设置未勾选状态时，方括号之间会有一个空格[ ]，不要漏掉了。

参考资料

[1] https://guides.github.com/features/issues/

[2] https://zhuanlan.zhihu.com/p/75691927

[3] https://blog.csdn.net/lovewinner/article/details/80763629

[4] https://www.jianshu.com/p/5ba1e7f5ad70

本部分内容贡献者

雪山凌狐、taotieren、吴烜